<h1>Getting Started with XORP</h1>

<p>This short guide is aimed at people new to XORP understand what XORP
does and how to use it.  It's a work in progress - please let us know
what additional help you would find useful.

<p><UL>
<LI><a href="#getting">Getting XORP</a>
<LI><a href="#os">Supported Operating Systems</a>
<LI><a href="#compiling">Compiling XORP from source</a>
<LI><a href="#validating">Validating a XORP Compilation</a>
<LI><a href="#running">Running XORP</a>
<LI><a href="#configuring">Configuring XORP</a>
</UL>

<P>

<a name="getting"></a><h2>Getting XORP</h2>

<P>There are several ways to try out XORP.
<UL>
<LI><a href="http://github.com/greearb/xorp.ct/downloads">Download</a> a pre-built release.</li>
<LI>Get <a href="http://github.com/greearb/xorp.ct/downloads">released source package</a>
    and <a href="#compiling">compile</a> it.</li>
<LI>Get the <a href="scm.html">current source snapshot</a> and <a href="#compiling">compile</a> it.</li>
<LI>Download a <a href="livecd.html">live CD</a>, and try out a precompiled release.</li>
</UL>

<p>If you want to develop new functionality for XORP, you'll obviously
need to compile from source, but the live CD provides a way to try
XORP out without needing to worry about having the right compilers or
operating system installed.


<a name="os"></a><h2>Supported Operating Systems</h2>

<P>
XORP should be fairly portable.  At the present time, the main
development platforms for XORP are FreeBSD and Linux.  XORP should run
on all recent versions of FreeBSD, and on most versions of Linux with a
2.6.x kernel.

<P>
XORP also appears to work on DragonFlyBSD, NetBSD, OpenBSD,
but if you want to
use it for multicast routing make sure that the kernel has the
appropriate support. If you try XORP on another platform, let us know
how you fare.  See <a href="porting.html">porting</a> if you're
interested in porting XORP to a new platform.
<P>
Recently, support for XORP on Windows was re-added.  See the
BUILD_NOTES in the xorp/ directory for more information.
<P>

<a name="compiling"></a><h2>Compiling XORP from source</h2>

<P>
After downloading the source, change to the 'xorp'
directory and read the BUILD_NOTES file.
<P>
Briefly:<br><pre>
cd xorp
scons
scons install
</pre>

<a name="validating"></a><h2>Validating a XORP Compilation</h2>
<P>
Assuming the compilation completed without errors, you can run some
self-tests:<br><pre>
scons check
</pre>
<P>

<a name="running"></a><h2>Running XORP</h2>
<P>
XORP tries to hide from the operator the internal structure of the
software, so that the operator only needs to know the right commands
to use to configure the router.  The operator should not need to know
that XORP is internally composed of multiple processes, nor what those
processes do.  All the operator needs to see is a single router
configuration file that determines the startup configuration, and a
single command line interface that can be used to configure XORP.
<P>
There is a single XORP process that manages the whole XORP router -
this is called <B>xorp_rtrmgr</B> (short for XORP Router Manager).  If
you built XORP from source using the defaults, the xorp_rtrmgr binary
will be in the rtrmgr subdirectory.
<P>
xorp_rtrmgr will expect to find a configuration file in the same
directory it is started from.  By default this configuration file is
called <B>config.boot</B>.  There are several sample configuration files in
the rtrmgr/config directory - please <B>do not</B> use these without tailoring
the IP addresses, interfaces and routing protocols to match your local
network environment.  You can specify a different filename for the
configuration file using the -b command line flag.  The -N "no
execute" flag will cause xorp_rtrmgr to startup and pretend the router
is operating normally, but to not actually start any processes.  This
can be used to check configuration files.
<P>
Typically xorp_rtrmgr must be run as root.  This is because it starts
up processes that need privileged access to insert routes into
the forwarding path in the kernel.
<P>
To interact with the router via the command line interface, the
operator uses the XORP command shell <B>xorpsh</B>.  If you compiled
from source, this should also be in the rtrmgr subdirectory.  Xorpsh
should not normally be run as root, but if a user is going to change
the configuration of the router (as opposed to simply monitor the
router's operation) then they need to be in the "xorp" Unix group.
<P>
The "help" command provides basic online help. The <a
href="releases/current/docs/user_manual/user_manual.pdf">XORP user
manual</a> (PDF) provides more detailed information about how to use xorpsh,
as well as information on how to configure specific routing protocols,
interface IP addresses, and so forth.

<a name="configuring"></a><h2>Configuring XORP</h2>
<P>
A XORP router must be configured to perform the desired operations.
The configuration information can be provided in one of the two ways:
<UL>
<LI>Use a configuration file when the rtrmgr is started.
    By default, the rtrmgr will load the configuration from file
    "config.boot" in the XORP installation directory.
    This file can be specified by the "-b &lt;filename&gt;" command line
    option:
<PRE>
    xorp_rtrmgr -b my_config.boot
</PRE>

    See <A href="releases/current/docs/config/">
    rtrmgr/config/</A> for a set of example configuration files.
    Note that these files MUST be modified before use.

<LI>Use the xorpsh command line interface after the rtrmgr is started.
    The xorpsh has to be in configurational mode:
<PRE>
    user@hostname> configure 
    Entering configuration mode.
    There are no other users in configuration mode.
    [edit]
    user@hostname# 
</PRE>

   On UNIX, only a user who belongs to group "xorp" can run xorpsh
   in configurational mode.
   It should be noted that command line completion in the xorpsh
   does greatly simplify configuration.
</UL>

<p>A mixture of both methods is permissible. For example,
a configuration file can also be loaded from within the xorpsh.

<H2>Network Interfaces</H2>

A XORP router will only use interfaces that it has been explicitly
configured to use. Even for protocols such as BGP that are agnostic to
interfaces, if the next-hop router for a routing entry is not through
a configured interface routes the route will not be installed.
For protocols that are explicitly aware of interfaces only configured
interfaces will be used.
<P>
Every physical and virtual network device in the system is considered to be an
"interface". Every interface can contain a single virtual interface (VIF).  The VIF structure
was originally implemented to allow multiple VIFS per interface, but in practice
that is not supported.  So, have the VIF name be the same as the interface name.
A virtual interface is configured with the address
or addresses that should be used. At each level in the configuration
hierarchy ("interface", "vif" and "address") this part of the configuration
is implicitly enabled.

<PRE>
interfaces {
    restore-original-config-on-shutdown: false
    interface dc0 {
	description: "data interface"
	disable: false
	/* default-system-config */
	vif dc0 {
	    disable: false
	    address 10.10.10.10 {
		prefix-length: 24
		broadcast: 10.10.10.255
		disable: false
	    }
/*
	    address 2001:DB8:10:10:10:10:10:10 {
		prefix-length: 64
		disable: false
	    }
*/
	}
    }
}
</PRE>

<P>
We recommend that you select the interfaces that you want to use on
your system and configure them as above. If you are configuring an
interface that is currently being used by the the system make sure
that there is no mismatch in the "address", "prefix-length" and
"broadcast" arguments.
If the "default-system-config" statement is used, it
instructs the FEA that the interface should be configured by using
the existing interface information from the underlying system.
In that case, the "vif"s and "address"es must not be configured.

<H3>Forwarding Engine Abstraction</H3>

It is a requirement to explicitly enable forwarding for each
protocol family.

<PRE>
fea {
    unicast-forwarding4 {
        disable: false
    }

    unicast-forwarding6 {
        disable: false
    }
}
</PRE>

If IPv4 and IPv6 forwarding are required you will require the configuration
above.

<P>
Now that we have configured the interfaces and enabled forwarding we
need to configure some routing protocols.

<H3>Protocols</H3>

<H4>Static Routes</H4>

This is the simplest routing protocol in XORP. It allows the
installation of unicast or multicast static routes (either IPv4 or IPv6).
Note that in case of multicast the routes are installed only in the user-level
Multicast Routing Information Base and are used for multicast-specific
reverse-path information by multicast routing protocols such as PIM-SM.

<PRE>
protocols {
    static {
	route 10.20.0.0/16 {
	    next-hop: 10.10.10.20
	    metric: 1
	}
	mrib-route 10.20.0.0/16 {
	    next-hop: 10.10.10.30
	    metric: 1
	}
/*
	route 2001:DB8:AAAA:20::/64 {
	    next-hop: 2001:DB8:10:10:10:10:10:20
	    metric: 1
	}
	mrib-route 2001:DB8:AAAA:20::/64 {
	    next-hop: 2001:DB8:10:10:10:10:10:30
	    metric: 1
	}
*/
    }
}
</PRE>

<H4>Routing Information Protocol</H4>

In order to run RIP it is sufficient to specify the "interface"s, "vif"s
and "address"es on which RIP is enabled. Remember that each "address"
must be explicitly configured.

<P>
If you wish to announce routes then it is necessary to "export" the
routes that are to be announced. For example, "connected" and "static".

<P>
<U>Note</U>: Starting with XORP Release-1.2 policy is used to export
routes into RIP with the "export" statement.  Prior to XORP
Release-1.2 the "export" statement was used with a different syntax.

<PRE>
policy {
    /* Describe connected routes for redistribution */
    policy-statement connected {
	term export {
	    from {
		protocol: "connected"
	    }
	}
    }
}

policy {
    /* Describe static routes for redistribution */
    policy-statement static {
	term export {
	    from {
		protocol: "static"
	    }
	}
    }
}

protocols {
    rip {
/* Redistribute routes for connected interfaces */
/*
	export: "connected"
*/
/* Redistribute static routes */
/*
	export: "static"
*/
/* Redistribute connected and static routes */
/*
	export: "connected,static"
*/

/* Run on specified network interface addresses */
/*
	interface dc0 {
	    vif dc0 {
		address 10.10.10.10 {
		    disable: false
		}
	    }
	}
*/
    }
}
</PRE>

<H4>Open Shortest Path First</H4>

In order to run OSPF Version 2 or 3 the "router-id" must be
specified, it is a unique IPv4 address within the Autonomous
System. The smallest IP address of an interface belonging to the
router is a good choice.
<P>
OSPF splits networks into areas so an "area" must be configured.

<P>
Configure one or more of the routers configured interface/vif/address
in this area. In the OSPF Version 3 case an address is not required.

<P><U>Note</U>: The 4 in "ospf4" refers to the IPv4 address family.

<PRE>
protocols {
    ospf4 {
	router-id: 10.10.10.10

	area 0.0.0.0 {
	    interface dc0 {
		vif dc0 {
		    address 10.10.10.10 {
		    }
		}
	    }
	}
    }
}
</PRE>

<P><U>Note</U>: The 6 in "ospf6" refers to the IPv6 address family. OSPFv3
may run multiple instances of OSPF in the same process, therefore the "ospf6"
keyword must be followed by an integer instance ID.

<PRE>
protocols {
    ospf6 0 {
	router-id: 10.10.10.10

	area 0.0.0.0 {
	    interface dc0 {
		vif dc0 {
		}
	    }
	}
    }
}
</PRE>

<H4>Border Gateway Protocol</H4>

In order to run BGP the "bgp-id" (BGP Identifier) and "local-as"
(Autonomous System number) must be specified.
<P>
The "peer" statement specifies a peering. The argument to the peer
statement is the IP address of the peer. The "local-ip" is the IP
address that TCP should use. The "as" is the Autonomous System Number
of the peer.

<PRE>
protocols {
    bgp {
	bgp-id: 10.10.10.10
	local-as: 65002

	peer 10.30.30.30 {
	    local-ip: 10.10.10.10
	    as: 65000
	    next-hop: 10.10.10.20
/*
	    local-port: 179
	    peer-port: 179
*/
	    /* holdtime: 120 */
	    /* disable: false */

	    /* IPv4 unicast is enabled by default */
	    /* ipv4-unicast: true */

	    /* Optionally enable other AFI/SAFI combinations */
	    /* ipv4-multicast: true */
            /* ipv6-unicast: true */
            /* ipv6-multicast: true */
	}
    }
}
</PRE>


<H4>Multicast Forwarding Engine Abstraction</H4>

The MFEA must be configured if the XORP router is to be used for multicast
routing. The MFEA for IPv4 and IPv6 are configured separately.
<P>
In the configuration we must explicitly configure the entity itself, and
each "vif". The "traceoptions" section is used to explicitly enable
log information that can be used for debugging purpose.

<PRE>
plumbing {
    mfea4 {
	disable: false
	interface dc0 {
	    vif dc0 {
		disable: false
	    }
	}
	interface register_vif {
	    vif register_vif {
		/* Note: this vif should be always enabled */
		disable: false
	    }
	}
	traceoptions {
	    flag all {
		disable: false
	    }
	}
    }
}

plumbing {
    mfea6 {
	disable: false
	interface dc0 {
	    vif dc0 {
		disable: false
	    }
	}
	interface register_vif {
	    vif register_vif {
		/* Note: this vif should be always enabled */
		disable: false
	    }
	}
	traceoptions {
	    flag all {
		disable: false
	    }
	}
    }
}
</PRE>


<P>
Note that the interface/vif named "register_vif" is special.
If PIM-SM is configured, then "register_vif" must be enabled
in the MFEA.

<H4>Internet Group Management Protocol/Multicast Listener Discovery</H4>

IGMP/MLD should be configured if the XORP router is to be used for multicast
routing and if we want to track multicast group membership for directly
connected subnets. Typically this is the case for a multicast router,
therefore it should be enabled. IGMP and MLD are configured separately:
IGMP is used for tracking IPv4 multicast members; MLD is used for tracking
IPv6 multicast members.
<P>
In the configuration we must explicitly configure each entity and
each "vif". The "traceoptions" section is used to explicitly enable
log information that can be used for debugging purpose.

<PRE>
protocols {
    igmp {
	disable: false
	interface dc0 {
	    vif dc0 {
		disable: false
		/* version: 2 */
		/* enable-ip-router-alert-option-check: false */
		/* query-interval: 125 */
		/* query-last-member-interval: 1 */
		/* query-response-interval: 10 */
		/* robust-count: 2 */
	    }
	}
	traceoptions {
	    flag all {
		disable: false
	    }
	}
    }
}

protocols {
    mld {
	disable: false
	interface dc0 {
	    vif dc0 {
		disable: false
		/* version: 1 */
		/* enable-ip-router-alert-option-check: false */
		/* query-interval: 125 */
		/* query-last-member-interval: 1 */
		/* query-response-interval: 10 */
		/* robust-count: 2 */
	    }
	}
	traceoptions {
	    flag all {
		disable: false
	    }
	}
    }
}
</PRE>

A number of parameters have default values, therefore
they don't have to be configured (those parameters are commented-out
in the above sample configuration).
<P>
The "version" parameter is used to configure the MLD/IGMP protocol
version per virtual interface.
<P>
The "enable-ip-router-alert-option-check" parameter is used to
enable the IP Router Alert option check per virtual interface.
<P>
The "query-interval" parameter is used to configure (per virtual
interface) the interval (in seconds) between general queries sent by the
querier.
<P>
The "query-last-member-interval" parameter is used to configure (per
virtual interface) the maximum response time (in seconds) inserted into
group-specific queries sent in response to leave group messages. It is
also the interval between group-specific query messages.
<P>
The "query-response-interval" parameter is used to configure (per
virtual interface) the maximum response time (in seconds) inserted into
the periodic general queries.
<P>
The "robust-count" parameter is used to configure the robustness
variable count that allows tuning for the expected packet loss on a
subnet.
<P>
Note that in case of IGMP each enabled interface must have a valid IPv4
address. In case of MLD each enabled interface must have a valid
link-local IPv6 address.

<H4>Protocol Independent Multicast - Sparse Mode</H4>

PIM-SM should be configured if the XORP router is to be used for
multicast routing in PIM-SM domain. PIM-SM for IPv4 and IPv6 are
configured separately. At minimum, the entity itself and the
virtual interfaces should be configured, as well as the mechanism for obtaining
the Candidate-RP set (either the Bootstrap mechanism, or a static-RP set).

<PRE>
protocols {
    pimsm4 {
	disable: false
	interface dc0 {
	    vif dc0 {
		disable: false
		/* enable-ip-router-alert-option-check: false */
		/* dr-priority: 1 */
		/* hello-period: 30 */
		/* hello-triggered-delay: 5 */
		/* alternative-subnet 10.40.0.0/16 */
	    }
	}
	interface register_vif {
	    vif register_vif {
		/* Note: this vif should be always enabled */
		disable: false
	    }
	}

	static-rps {
	    rp 10.60.0.1 {
		group-prefix 224.0.0.0/4 {
		    /* rp-priority: 192 */
		    /* hash-mask-len: 30 */
		}
	    }
	}

	bootstrap {
	    disable: false
	    cand-bsr {
		scope-zone 224.0.0.0/4 {
		    /* is-scope-zone: false */
		    cand-bsr-by-vif-name: "dc0"
		    /* cand-bsr-by-vif-addr: 10.10.10.10 */
		    /* bsr-priority: 1 */
		    /* hash-mask-len: 30 */
		}
	    }

	    cand-rp {
		group-prefix 224.0.0.0/4 {
		    /* is-scope-zone: false */
		    cand-rp-by-vif-name: "dc0"
		    /* cand-rp-by-vif-addr: 10.10.10.10 */
		    /* rp-priority: 192 */
		    /* rp-holdtime: 150 */
		}
	    }
	}

	switch-to-spt-threshold {
	    /* approx. 1K bytes/s (10Kbps) threshold */
	    disable: false
	    interval: 100
	    bytes: 102400
	}

	traceoptions {
	    flag all {
		disable: false
	    }
	}
    }
}

protocols {
    pimsm6 {
	disable: false
	interface dc0 {
	    vif dc0 {
		disable: false
		/* enable-ip-router-alert-option-check: false */
		/* dr-priority: 1 */
		/* hello-period: 30 */
		/* hello-triggered-delay: 5 */
		/* alternative-subnet 2001:DB8:40:40::/64 */
	    }
	}
	interface register_vif {
	    vif register_vif {
		/* Note: this vif should be always enabled */
		disable: false
	    }
	}

	static-rps {
	    rp 2001:DB8:50:50:50:50:50:50 {
		group-prefix ff00::/8 {
		    /* rp-priority: 192 */
		    /* hash-mask-len: 126 */
		}
	    }
	}

	bootstrap {
	    disable: false
	    cand-bsr {
		scope-zone ff00::/8 {
		    /* is-scope-zone: false */
		    cand-bsr-by-vif-name: "dc0"
		    /* cand-bsr-by-vif-addr: 2001:DB8:10:10:10:10:10:10 */
		    /* bsr-priority: 1 */
		    /* hash-mask-len: 126 */
		}
	    }

	    cand-rp {
		group-prefix ff00::/8 {
		    /* is-scope-zone: false */
		    cand-rp-by-vif-name: "dc0"
		    /* cand-rp-by-vif-addr: 2001:DB8:10:10:10:10:10:10 */
		    /* rp-priority: 192 */
		    /* rp-holdtime: 150 */
		}
	    }
	}

	switch-to-spt-threshold {
	    /* approx. 1K bytes/s (10Kbps) threshold */
	    disable: false
	    interval: 100
	    bytes: 102400
	}

	traceoptions {
	    flag all {
		disable: false
	    }
	}
    }
}
</PRE>

<P>
A number of parameters have default values, therefore
they don't have to be configured (those parameters are commented-out
in the above sample configuration).
<P>
Note that the interface/vif named "register_vif" is special
If PIM-SM is configured, then "register_vif" must be enabled.
<P>
The "enable-ip-router-alert-option-check" parameter is used to
enable the IP Router Alert option check per virtual interface.
<P>
The "dr-priority" parameter is used to configure the Designated Router
priority per virtual interface (note that in case of "register_vif"
it is not used).
<P>
The "hello-period" parameter is used to configure the PIM Hello messages
period (in seconds) per virtual interface.
It must be an integer between 1 and 18724.
<P>
The "hello-triggered-delay" parameter is used to configure the randomized
triggered delay of PIM Hello messages (in seconds) per virtual interface.
It must be an integer between 1 and 255.
<P>
The "alternative-subnet" statement is used to add "alternative subnets"
to a network interface. For example, if you want to make incoming traffic
with a non-local source address appear as it is coming from a local subnet,
then "alternative-subnet" can be used. Typically, this is needed as a
work-around solution when we use uni-directional interfaces for
receiving traffic (e.g., satellite links).
Note: use "alternative-subnet" with extreme care, only if you know
what you are really doing!
<P>
If PIM-SM uses static RPs, those can be configured within the
"static-rps" section. For each RP, an "rp" section is needed, and each
section should contain the multicast prefix address the static RP is
configured with. The RP priority can be modified with the "rp-priority"
parameter.
<P>
If PIM-SM uses the Bootstrap mechanism to obtain the Candidate-RP set,
that can be configured in the "bootstrap" section.
If the XORP router is to be used as a Candidate-BSR, this should be
specified in the "cand-bsr" section.
For a router to be a Candidate-BSR it must advertise for
each zone (scoped or non-scoped) the associated multicast prefix address.
The "cand-bsr" section should contain "scope-zone" statements for each
multicast prefix address.
The vif name with the address that is to be used as the Candidate-BSR
is specified by the "cand-bsr-by-vif-name" statement.
The particular vif's address can be specified by the
"cand-bsr-by-vif-addr" statement. If the
"cand-bsr-by-vif-addr" statement is omitted, a domain-wide
address (if exists) that belongs to that interface is chosen by the router
itself.
The Candidate-BSR priority can be modified with the "bsr-priority"
parameter.
<P>
If the XORP router is to be a Candidate-RP, this should be specified
in the "cand-rp" section.
For a router to be a Candidate-RP it must advertise for
each zone (scoped or non-scoped) the associated multicast prefix address.
The "cand-rp" section should contain "group-prefix" statements for each
multicast prefix address.
The vif name with the address that is to be used as the Candidate-RP
is specified by the "cand-rp-by-vif-name" statement.
The particular vif's address can be specified by the
"cand-rp-by-vif-addr" statement. If the
"cand-rp-by-vif-addr" statement is omitted, a domain-wide
address (if exists) that belongs to that interface is chosen by the router
itself.
The Candidate-RP priority can be modified with the
"rp-priority" parameter; the Candidate-RP holdtime can be modified
with the "rp-holdtime" parameter.
<P>
The "is-scope-zone" parameter is used to specify whether a Candidate-BSR
"scope-zone" or a Candidate-RP "group-prefix" is scoped. Currently,
scoped zones are not well tested, hence it is recommended "scope-zone"
is always set to "false".
Note that typically the "hash-mask-len" should not be modified; if you
don't know what "hash-mask-len" is used for, don't modify it!
<P>
The "switch-to-spt-threshold" section can be used to specify the
multicast data bandwidth threshold used by the last-hop PIM-SM routers
and the RPs to initiate shortest-path switch toward the multicast source.
Parameter "interval" is used to specify the periodic measurement interval;
parameter "bytes" is used to specify the threshold in number of bytes
within the measurement interval. It is recommended that the measurement
interval is not too small, and should be on the order of tens of seconds.
The smallest accepted value is 3 seconds.
If the shortest-path switch should happen right after the first packet is
forwarded, then "bytes" should be set to 0.
<P>
The "traceoptions" section is used to explicitly enable log information
that can be used for debugging purpose.
<P>
Note that in case of PIM-SM for IPv4 each enabled interface must have a
valid IPv4 address. In case of PIM-SM for IPv6 each enabled interface
must have a valid link-local and a valid domain-wide IPv6 addresses.

<H4>FIB2MRIB</H4>

The FIB2MRIB module is used to obtain the Forwarding Information Base
information from the underlying system (via the FEA), and to propagate
it to the MRIB, so it can be used by multicast routing protocols
such as PIM-SM. Typically, it is needed only if the unicast routing
protocols (if any) on that router do not inject routes into the MRIB.

<PRE>
protocols {
    fib2mrib {
	disable: false
    }
}
</PRE>

